<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>pthread_mutexattr_setprotocol</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_1540">&nbsp;</a>NAME</h4><blockquote>
pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol
- set and get protocol attribute of mutex attribute object
(<b>REALTIME THREADS</b>)
</blockquote><h4><a name = "tag_000_007_1541">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="pthread.h.html">pthread.h</a>&gt;

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *<i>attr</i>,
    int <i>protocol</i>);
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *<i>attr</i>,
    int *<i>protocol</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1542">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>pthread_mutexattr_setprotocol()</i>
and
<i>pthread_mutexattr_getprotocol()</i>
functions, respectively, set and get the protocol attribute of a mutex
attribute object pointed to by
<i>attr</i>
which was previously created by the function
<i><a href="pthread_mutexattr_init.html">pthread_mutexattr_init()</a></i>.
<p>
The
<i>protocol</i>
attribute defines the protocol to be followed in utilising mutexes.
The value of
<i>protocol</i>
may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or
PTHREAD_PRIO_PROTECT, which are defined by the header
<i><a href="pthread.h.html">&lt;pthread.h&gt;</a></i>.
<p>
When a thread owns a mutex with the PTHREAD_PRIO_NONE
protocol attribute, its priority and scheduling are not affected
by its mutex ownership.
<p>
When a thread is blocking higher priority threads because of owning one or
more mutexes with the PTHREAD_PRIO_INHERIT
protocol attribute, it executes at the higher of its priority
or the priority of the highest priority thread waiting on any of the mutexes
owned by this thread and initialised with this protocol.
<p>
When a thread owns one or more mutexes initialised with the
PTHREAD_PRIO_PROTECT
protocol, it executes at the higher of its priority or the highest
of the priority ceilings of all the mutexes
owned by this thread and initialised with this attribute,
regardless of whether other threads are blocked on any of these
mutexes or not.
<p>
While a thread is holding a mutex which has been initialised with the
PRIO_INHERIT or PRIO_PROTECT protocol attributes,
it will not be subject to being moved
to the tail of the scheduling queue at its priority
in the event that its original priority is changed,
such as by a call to
<i><a href="sched_setparam.html">sched_setparam()</a></i>.
Likewise,
when a thread unlocks a mutex that has been initialised with the
PRIO_INHERIT or PRIO_PROTECT protocol attributes,
it will not be subject to being moved
to the tail of the scheduling queue at its priority
in the event that its original priority is changed.
<p>
If a thread simultaneously owns several mutexes
initialised with different protocols,
it will execute at the highest of the priorities
that it would have obtained by each of these protocols.
<p>
When a thread makes a call to
<i><a href="pthread_mutex_lock.html">pthread_mutex_lock()</a></i>,
if the symbol _POSIX_THREAD_PRIO_INHERIT
is defined and the mutex was
initialised with the protocol attribute having the value
PTHREAD_PRIO_INHERIT, when the calling thread is blocked
because the mutex is owned by another thread,
that owner thread will inherit the priority level
of the calling thread as long as it continues to own the mutex.
The implementation updates its execution priority
to the maximum of its assigned priority and all its inherited priorities.
Furthermore, if this owner thread itself becomes blocked on another mutex,
the same priority inheritance effect will be propagated
to this other owner thread, in a recursive manner.
</blockquote><h4><a name = "tag_000_007_1543">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion, the
<i>pthread_mutexattr_setprotocol()</i>
and
<i>pthread_mutexattr_getprotocol()</i>
functions return zero.
Otherwise, an error number is returned to indicate the error.
</blockquote><h4><a name = "tag_000_007_1544">&nbsp;</a>ERRORS</h4><blockquote>
The 
<i>pthread_mutexattr_setprotocol()</i>
and
<i>pthread_mutexattr_getprotocol()</i>
functions will fail if:
<dl compact>

<dt>[ENOSYS]<dd>
Neither one of the options _POSIX_THREAD_PRIO_PROTECT and
_POSIX_THREAD_PRIO_INHERIT is defined and the implementation does not
support the function.

<dt>[ENOTSUP]<dd>
The value specified by
<i>protocol</i>
is an unsupported value.

</dl>
<p>
The
<i>pthread_mutexattr_setprotocol()</i>
and
<i>pthread_mutexattr_getprotocol()</i>
functions may fail if:
<dl compact>

<dt>[EINVAL]<dd>
The value specified by
<i>attr</i>
ro
<i>protocol</i>
is invalid.

<dt>[EPERM]<dd>
The caller does not have the privilege to perform the operation.

</dl>
</blockquote><h4><a name = "tag_000_007_1545">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1546">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1547">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1548">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pthread_create.html">pthread_create()</a></i>,
<i><a href="pthread_mutex_init.html">pthread_mutex_init()</a></i>,
<i><a href="pthread_cond_init.html">pthread_cond_init()</a></i>,
<i><a href="pthread.h.html">&lt;pthread.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Threads Extension (1003.1c-1995)
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

